51.1.7 Custom Themes

Custom themes are collections of settings that can be enabled or disabled as a unit. You can use Custom themes to switch easily between various collections of settings, and to transfer such collections from one computer to another.

A Custom theme is stored as an Emacs Lisp source file. If the name of the Custom theme is name, the theme file is named name-theme.el. See Creating Custom Themes, for the format of a theme file and how to make one.

Type M-x customize-themes to switch to a buffer named *Custom Themes*, which lists the Custom themes that Emacs knows about. By default, Emacs looks for theme files in two locations: the directory specified by the variable custom-theme-directory (which defaults to ~/.emacs.d/), and a directory named etc/themes in your Emacs installation (see the variable data-directory). The latter contains several Custom themes which are distributed with Emacs, which customize Emacs’s faces to fit various color schemes. (Note, however, that Custom themes need not be restricted to this purpose; they can be used to customize variables too.)

If you want Emacs to look for Custom themes in some other directory, add the directory name to the list variable custom-theme-load-path. Its default value is (custom-theme-directory t); here, the symbol custom-theme-directory has the special meaning of the value of the variable custom-theme-directory, while t stands for the built-in theme directory etc/themes. The themes listed in the *Custom Themes* buffer are those found in the directories specified by custom-theme-load-path.

In the *Custom Themes* buffer, you can activate the checkbox next to a Custom theme to enable or disable the theme for the current Emacs session. When a Custom theme is enabled, all of its settings (variables and faces) take effect in the Emacs session. To apply the choice of theme(s) to future Emacs sessions, type C-x C-s (custom-theme-save) or use the ‘[Save Theme Settings]’ button.

When you first enable a Custom theme, Emacs displays the contents of the theme file and asks if you really want to load it. Because loading a Custom theme can execute arbitrary Lisp code, you should only say yes if you know that the theme is safe; in that case, Emacs offers to remember in the future that the theme is safe (this is done by saving the theme file’s SHA-256 hash to the variable custom-safe-themes; if you want to treat all themes as safe, change its value to t). Themes that come with Emacs (in the etc/themes directory) are exempt from this check, and are always considered safe.

Setting or saving Custom themes actually works by customizing the variable custom-enabled-themes. The value of this variable is a list of Custom theme names (as Lisp symbols, e.g., tango). Instead of using the *Custom Themes* buffer to set custom-enabled-themes, you can customize the variable using the usual customization interface, e.g., with M-x customize-option. Note that Custom themes are not allowed to set custom-enabled-themes themselves.

Any customizations that you make through the customization buffer take precedence over theme settings. This lets you easily override individual theme settings that you disagree with. If settings from two different themes overlap, the theme occurring earlier in custom-enabled-themes takes precedence. In the customization buffer, if a setting has been changed from its default by a Custom theme, its ‘State’ display shows ‘THEMED’ instead of ‘STANDARD’.

You can enable a specific Custom theme in the current Emacs session by typing M-x load-theme. This prompts for a theme name, loads the theme from the theme file, and enables it. If a theme file has been loaded before, you can enable the theme without loading its file by typing M-x enable-theme. To disable a Custom theme, type M-x disable-theme.

To see a description of a Custom theme, type ? on its line in the *Custom Themes* buffer; or type M-x describe-theme anywhere in Emacs and enter the theme name.